<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">
<html>
<head>
<!-- Copyright 1997 The Open Group, All Rights Reserved -->
<title>pax</title>
</head><body bgcolor=white>
<center>
<font size=2>
The Single UNIX &reg; Specification, Version 2<br>
Copyright &copy; 1997 The Open Group

</font></center><hr size=2 noshade>
<h4><a name = "tag_001_014_1688">&nbsp;</a>NAME</h4><blockquote>
pax - portable archive interchange
</blockquote><h4><a name = "tag_001_014_1689">&nbsp;</a>SYNOPSIS</h4><blockquote>
<pre><code>

pax <b>[</b>-cdnv<b>][</b>-f <i>archive</i><b>][</b>-s <i>replstr</i><b>]</b>...<b>[</b><i>pattern</i>...<b>]</b>

pax -r<b>[</b>-cdiknuv<b>][</b>-f <i>archive</i><b>][</b>-o <i>options</i><b>]</b>...<b>[</b>-p <i>string</i><b>]</b>...
<b>[</b>-s <i>replstr</i><b>]</b>...<b>[</b><i>pattern</i>...<b>]</b>

pax -w<b>[</b>-dituvX<b>][</b>-b <i>blocksize</i><b>][[</b>-a<b>][</b>-f <i>archive</i><b>][</b>-o <i>options</i><b>]</b>...
<b>[</b>-s <i>replstr</i><b>]</b>...<b>[</b>-x <i>format</i><b>][</b><i>file</i>...<b>]</b>

pax -r -w<b>[</b>-diklntuvX<b>][</b>-p <i>string</i><b>]</b>...<b>[</b>-s <i>replstr</i><b>]</b>...<b>[</b><i>file</i>...<b>]</b><i>
directory
</i></code>
</pre>
</blockquote><h4><a name = "tag_001_014_1690">&nbsp;</a>DESCRIPTION</h4><blockquote>
The
<i>pax</i>
utility reads, writes and writes lists of the members of archive
files and copy directory hierarchies.
A variety of archive formats
are supported; see the
<b>-x</b>&nbsp;<i>format</i>
option.
<p>
The action to be taken depends on the presence of the
<b>-r</b>
and
<b>-w</b>
options.
The four combinations of
<b>-r</b>
and
<b>-w</b>
are referred to as the four modes of operation:
<i>list</i>,
<i>read</i>,
<i>write</i>
and
<i>copy</i>
modes, corresponding respectively to the four forms shown in the
SYNOPSIS section.
<dl compact>

<dt>list<dd>In list mode (when neither
<b>-r</b>
nor
<b>-w</b>
are specified),
<i>pax</i>
writes the names of the members of the archive file read from
the standard input, with pathnames matching the specified
patterns, to standard output.
If a named file is of
type directory, the file hierarchy rooted at that file
will be written out as well.

<dt>read<dd>In read mode (when
<b>-r</b>
is specified, but
<b>-w</b>
is not),
<i>pax</i>
extracts the members of the archive file read from
the standard input, with pathnames matching the specified patterns.
If an extracted file is of type directory, the
file hierarchy rooted at that file will be extracted as well.
The extracted files is created relative to the
current file hierarchy.

The ownership, access and modification times,
and file mode of the restored files
are discussed under the
<b>-p</b>
option.


<dt>write<dd>In write mode (when
<b>-w</b>
is specified, but
<b>-r</b>
is not),
<i>pax</i>
writes the contents of the file operands to the
standard output in an archive format.
If no
<i>file</i>
operands are specified, a list of files to copy,
one per line, will be read from the standard input.
A file of type directory
will include all of the files in the file hierarchy rooted
at the file.

<dt>copy<dd>In copy mode (when both
<b>-r</b>
and
<b>-w</b>
are specified),
<i>pax</i>
copies the file operands to the destination directory.

If no
<i>file</i>
operands are specified, a list of files to copy,
one per line, will be read from the standard input.
A file of type directory will include all of the files in
the file hierarchy rooted at the file.

The effect of the copy is as if the copied files
were written to an archive file and then subsequently
extracted, except that there may be hard links between the
original and the copied files.
If the destination directory
is a subdirectory of one of the files to be copied, the
results are unspecified.
If the destination directory is
a file of a type not defined by the <b>XSH</b> specification, the results
are implementation-dependent;
otherwise it is an error
for the file named by the directory operand not to exist,
not be writable by the user, or not be a file of type directory.

</dl>
<p>
In read or copy modes,
if intermediate directories are
necessary to extract an archive member,
<i>pax</i>
will perform actions equivalent to the <b>XSH</b> specification
<i><a href="../xsh/mkdir.html">mkdir()</a></i>
function, called with the following arguments:
<ul>
<p>
<li>
the intermediate directory used as the
<i>path</i>
argument
<p>
<li>
the value of the bitwise inclusive OR of S_IRWXU,
S_IRWXG and S_IRWXO as the
<i>mode</i>
argument.
<p>
</ul>
<p>
If any specified
<i>pattern</i>
or
<i>file</i>
operands are not matched by at
least one file or archive member,
<i>pax</i>
will write a diagnostic message to standard error
for each one that did not match and exit with a non-zero exit status.
<p>
The supported archive formats are automatically detected on input.
The default output archive format is implementation-dependent.
<p>
A single archive can span multiple files.
The
<i>pax</i>
utility determines,
in an implementation-dependent manner, what file to read
or write as the next file.
<p>
If the selected archive format supports the specification of
linked files, it is an error if these files cannot be
linked when the archive is extracted.
Any of the various names in the archive that represent
a file can be used to select the file for extraction.
</blockquote><h4><a name = "tag_001_014_1691">&nbsp;</a>OPTIONS</h4><blockquote>
The
<i>pax</i>
utility supports the <b>XBD</b> specification, <a href="../xbd/utilconv.html#usg"><b>Utility Syntax Guidelines</b>&nbsp;</a> ,
except that the order of presentation of the
<b>-s</b>
options is significant.
<p>
The following options are supported:
<dl compact>

<dt><b>-r</b>
<dd>Read an archive file from standard input.

<dt><b>-w</b>
<dd>Write files to the standard output in the specified archive format.

<dt><b>-a</b>
<dd>Append files to the end of the archive.
It is implementation-dependent which
devices on the system support appending.
Additional file formats
unspecified by this specification
may impose restrictions on appending.

<dt><b>-b&nbsp;</b><i>blocksize</i>
<dd>
Block the output at a positive decimal integer number of
bytes per write to the archive file.
Devices and archive formats may impose restrictions on blocking.
Blocking is automatically determined on input.
Portable applications must not specify a
<i>blocksize</i>
value larger than 32256.
Default blocking when creating archives depends on the archive format.
(See the
<b>-x</b>
option below.)

<dt><b>-c</b>
<dd>Match all file or archive members except those specified by the
<i>pattern</i>
or
<i>file</i>
operands.

<dt><b>-d</b>
<dd>Cause files of type directory being copied or archived or
archive members of type directory being extracted to match
only the file or archive member itself and not the file
hierarchy rooted at the file.

<dt><b>-f&nbsp;</b><i>archive</i>
<dd>
Specify the pathname of the input
or output archive,
overriding the default standard input
(in list or read modes)
or standard output (write mode).

<dt><b>-i</b>
<dd>Interactively rename files or archive members.
For each archive member matching a
<i>pattern</i>
operand or file matching a
<i>file</i>
operand, a prompt will be written to the file
<b>/dev/tty</b>.
The prompt will contain the name of the file
or archive member, but the format is otherwise unspecified.
A line will then be read from
<b>/dev/tty</b>.
If this line is blank, the file or archive member will be skipped.
If this line consists of a single period,
the file or archive member will be processed with no
modification to its name.
Otherwise, its name will be
replaced with the contents of the line.
The
<i>pax</i>
utility will immediately exit with a non-zero exit status if
end-of-file is encountered when reading a response or if
<b>/dev/tty</b>
cannot be opened for reading and writing.

<dt><b>-k</b>
<dd>Prevent the overwriting of existing files.

<dt><b>-l</b>
<dd>(The letter ell.)
Link files.
In copy mode,
hard links will be made between the source
and destination file hierarchies whenever possible.

<dt><b>-n</b>
<dd>Select the first archive member that matches each
<i>pattern</i>
operand.
No more than one archive member will be matched
for each pattern (although members of type directory
will still match the file hierarchy rooted at that file).

<dt><b>-o&nbsp;</b><i>options</i>
<dd>
Provide information to the implementation
to modify the algorithm for extracting
or writing files that is specific to
the file format specified by
<b>-x</b>.
This issue does not specify any such options and a portable application
must not use the
<b>-o</b>
option.

<dt><b>-p&nbsp;</b><i>string</i>
<dd>
Specify one or more file characteristic options (privileges).
The
<i>string</i>
option-argument must be a string specifying file
characteristics to be retained or discarded on extraction.
The string consists of the specification characters
a,
e,
m,
o
and
p.
Other, implementation-dependent, characters can be included.
Multiple characteristics can be concatenated
within the same string and multiple
<b>-p</b>
options can be specified.
The meaning of the specification characters
are as follows:
<dl compact>

<dt>a<dd>Do not preserve file access times.

<dt>e<dd>Preserve the user ID, group ID, file mode bits (see
<b>file mode bits</b>
in the <b>XBD</b> specification, <a href="../xbd/glossary.html"><b>Glossary</b>&nbsp;</a> ), access time,
modification time and any other, implementation-dependent,
file characteristics.

<dt>m<dd>Do not preserve file modification times.

<dt>o<dd>Preserve the user ID and group ID.

<dt>p<dd>Preserve the file mode bits.
Other, implementation-dependent file-mode attributes may be preserved.

</dl>
<p>
In the preceding list, &quot;preserve&quot; indicates
that an attribute stored in the archive
will be given to the extracted file,
subject to the permissions of the invoking process;
otherwise, the attribute will be determined
as part of the normal file creation action.
<p>
If neither the
e
nor the
o
specification character is
specified, or the user ID and group ID are not preserved
for any reason,
<i>pax</i>
will not set the S_ISUID and S_ISGID
bits of the file mode.
<p>
If the preservation of any of these items fails for any reason,
<i>pax</i>
will write a diagnostic message to standard error.
Failure to preserve these items
will affect the final exit status, but will not cause the
extracted file to be deleted.
<p>
If file-characteristic letters in any of the
<i>string</i>
option-arguments are duplicated or conflict with each other,
the ones given last will take precedence.
For example, if
<b>-p eme</b>
is specified, file modification times will be preserved.
<br>
<br>
<dt><b>-s&nbsp;</b><i>replstr</i>
<dd>
Modify file or archive member names named by
<i>pattern</i>
or
<i>file</i>
operands according to the substitution expression
<i>replstr</i>,
using the syntax of the
<i><a href="ed.html">ed</a></i>
utility.
The concepts of &quot;address&quot; and &quot;line&quot; are
meaningless in the context of the
<i>pax</i>
utility, and must not be supplied.
The format is:
<pre><code>

-s /<i>old</i>/<i>new</i>/<b>[</b>gp<b>]
</b></code>
</pre>
where as in
<i><a href="ed.html">ed</a></i>,
<i>old</i>
is a basic regular expression and
<i>new</i>
can contain an ampersand, \<i>n</i> (where <i>n</i> is a digit)
backreferences,
or subexpression matching.
The
<i>old</i>
string also is permitted to contain
newline
characters.
<p>
Any non-null character can be used as a delimiter
(/
shown here).
Multiple
<b>-s</b>
expressions can be specified; the expressions will be applied in
the order specified,
terminating with the first successful substitution.
The optional trailing
g
is as defined in the
<i><a href="ed.html">ed</a></i>
utility.
The optional trailing
p
causes successful substitutions to be written to standard error.
File or archive member
names that substitute to the empty string are ignored when
reading and writing archives.
<br>
<dt><b>-t</b>
<dd>Cause the access times of the archived files to be the same
as they were before being read by
<i>pax</i>.
<br>
<dt><b>-u</b>
<dd>Ignore files that are older (having a less recent
file modification time) than a pre-existing file or
archive member with the same name.
In read mode,
an archive
member with the same name as a file in the file system
will be extracted if the archive member is newer than the file.
In write mode,
an archive file member with the
same name as a file in the file system will be
superseded if the file is newer than the archive member.
It is unspecified if this is accomplished by actual
replacement in the archive or by appending to the archive.
In copy mode,
the file in the destination hierarchy will be replaced by the
file in the source hierarchy
or by a link to the file in the source hierarchy
if the file in the source hierarchy is newer.
<br>
<dt><b>-v</b>
<dd>In list mode,
produce a verbose table of contents (see the STDOUT section).
Otherwise, write archive member pathnames to standard error (see
the STDERR section).
<br>
<dt><b>-x&nbsp;</b><i>format</i>
<dd>
Specify the output archive format.
The
<i>pax</i>
utility recognises the following formats:
<dl compact>

<dt><b>cpio</b><dd>The extended
<i><a href="cpio.html">cpio</a></i>
interchange format; see the EXTENDED DESCRIPTION section.
The default
<i>blocksize</i>
for this format for character special archive files is 5120.
Implementations support all
<i>blocksize</i>
values less than or equal to 32256
that are multiples of 512.

<dt><b>ustar</b><dd>The extended
<i><a href="tar.html">tar</a></i>
interchange format; see the EXTENDED DESCRIPTION section.
The default
<i>blocksize</i>
for this format for character special archive files
is 10240.
Implementations support all
<i>blocksize</i>
values less than or equal to 32256
that are multiples of 512.

</dl>
<p>
Implementation-dependent formats will specify a default
block size as well as any other block sizes supported
for character special archive files.
<p>
Any attempt to append to an archive file in a format different
from the existing archive format will cause
<i>pax</i>
to exit immediately with a non-zero exit status.
<br>
<dt><b>-X</b>
<dd>When traversing the file hierarchy specified by a pathname,
<i>pax</i>
will not descend into directories that have a different device ID
(<b>st_dev</b>,
see the <b>XSH</b> specification
<i><a href="../xsh/stat.html">stat()</a></i>).
<p>
</dl>
<p>
The options that operate on the names of files or archive members
(<b>-c</b>,
<b>-i</b>,
<b>-n</b>,
<b>-s</b>,
<b>-u</b>
and
<b>-v</b>)
interact as follows.
In read mode, the archive members are selected
based on the user-specified
<i>pattern</i>
operands as modified by the
<b>-c</b>,
<b>-n</b>
and
<b>-u</b>
options.
Then, any
<b>-s</b>
and
<b>-i</b>
options will modify, in that order,
the names of the selected files.
The
<b>-v</b>
option will write
names resulting from these modifications.
<p>
In write mode, the
files are selected based on the user-specified pathnames as
modified by the
<b>-n</b>
and
<b>-u</b>
options.
Then, any
<b>-s</b>
and
<b>-i</b>
options will, in that order, modify the names of these selected files.
The
<b>-v</b>
option will write names resulting from these modifications.
<p>
If both the
<b>-u</b>
and
<b>-n</b>
options are specified,
<i>pax</i>
does not consider a file selected unless it is newer than the file to
which it is compared.
</blockquote><h4><a name = "tag_001_014_1692">&nbsp;</a>OPERANDS</h4><blockquote>
The following operands are supported:
<dl compact>

<dt><i>directory</i><dd>
The destination directory pathname for copy mode.

<dt><i>file</i><dd>A pathname of a file to be copied or archived.

<dt><i>pattern</i><dd>A pattern matching one or more pathnames of archive members.
A pattern must be given in the name-generating notation
of the pattern matching notation in
<xref href=patmat><a href="chap2.html#tag_001_013">
Pattern Matching Notation
</a></xref>,
including the filename expansion rules in
<xref href=patfilx><a href="chap2.html#tag_001_013_003">
Patterns Used for Filename Expansion
</a></xref>.
The default, if no
<i>pattern</i>
is specified, is
to select all members in the archive.

</dl>
</blockquote><h4><a name = "tag_001_014_1693">&nbsp;</a>STDIN</h4><blockquote>
In write mode,
the standard input is used only if no
<i>file</i>
operands are specified.
It must be a text file containing a list of pathnames, one per line,
without leading or trailing
blank characters.
<p>
In list and read modes,
the standard input
must be an archive file.
<p>
Otherwise, the standard input will not be used.
</blockquote><h4><a name = "tag_001_014_1694">&nbsp;</a>INPUT FILES</h4><blockquote>
The input file named by the
<i>archive</i>
option-argument,
or standard input when the archive is read from there,
will be a file formatted according to
one of the specifications in the EXTENDED DESCRIPTION section
or some other, implementation-dependent, format.
<p>
The file
<b>/dev/tty</b>
is used to write prompts and read responses.
</blockquote><h4><a name = "tag_001_014_1695">&nbsp;</a>ENVIRONMENT VARIABLES</h4><blockquote>
The following environment variables affect the execution of
<i>pax</i>:
<dl compact>

<dt><i>LANG</i><dd>Provide a default value for the internationalisation variables
that are unset or null.
If
<i>LANG</i>
is unset or null, the corresponding value from the
implementation-dependent default locale will be used.
If any of the internationalisation variables contains an invalid setting, the
utility will behave as if none of the variables had been defined.

<dt><i>LC_ALL</i><dd>
If set to a non-empty string value,
override the values of all the other internationalisation variables.

<dt><i>LC_COLLATE</i><dd>
Determine the locale for the
behaviour of ranges, equivalence classes
and multi-character collating elements
used in the
pattern matching expressions for the
<i>pattern</i>
operand, the basic regular expression for the
<b>-s</b>
option, and the
extended regular expression defined for the
<b>yesexpr</b>
locale keyword in the LC_MESSAGES category.

<dt><i>LC_CTYPE</i><dd>
Determine the
locale for the interpretation of sequences of bytes of text data as
characters (for example, single- as opposed to multi-byte characters
in arguments and input files),
the behaviour of character classes
used in the extended regular expression defined for the
<b>yesexpr</b>
locale keyword in the LC_MESSAGES category,
and pattern matching.


<dt><i>LC_MESSAGES</i><dd>
Determine the locale for the processing of affirmative responses
that should be used to affect the format and contents of diagnostic
messages written to standard error.

<dt><i>LC_TIME</i><dd>
Determine the format and contents of date and time strings when the
<b>-v</b>
option is specified.

<dt><i>NLSPATH</i><dd>
Determine the location of message catalogues
for the processing of
<i>LC_MESSAGES .
</i>
</dl>
</blockquote><h4><a name = "tag_001_014_1696">&nbsp;</a>ASYNCHRONOUS EVENTS</h4><blockquote>
Default.
</blockquote><h4><a name = "tag_001_014_1697">&nbsp;</a>STDOUT</h4><blockquote>
In write mode, if
<b>-f</b>
is not specified, the
standard output will be the archive
formatted according to
one of the specifications in the EXTENDED DESCRIPTION section,
or some other implementation-dependent format.
(See
<b>-x</b>&nbsp;<i>format</i>.)
<p>
In list mode, the
table of contents of the selected archive members will be written to
standard output using the following format:
<code>
<p>
<tt>"%s\n"</tt>, &lt;<i>pathname</i>&gt;
</code>
<p>
If the
<b>-v</b>
option is specified in list mode, the table of contents of the selected
archive members will be written to standard output using the
following formats:
<p>
For pathnames representing hard links to previous members of the archive:
<code>
<p>
<tt>"%s<img src="../images/delta.gif" border=0>==<img src="../images/delta.gif" border=0>%s\n"</tt>, &lt;<i>ls -l listing</i>&gt;,
&lt;<i>linkname</i>&gt;
</code>
<p>
For all other pathnames:
<code>
<p>
<tt>"%s\n"</tt>, &lt;<i>ls -l listing</i>&gt;
</code>
<p>
where
&lt;<i>ls -l listing</i>&gt;
is the format specified by the
<i><a href="ls.html">ls</a></i>
utility
with the
<b>-l</b>
option.
When writing pathnames in this format, it is
unspecified what is written for fields for which the
underlying archive format does not have the correct information,
although the correct number of
blank-character-separated
fields will be written.
<p>
In list mode,
standard output will not be buffered more than a line at a time.
</blockquote><h4><a name = "tag_001_014_1698">&nbsp;</a>STDERR</h4><blockquote>
If
<b>-v</b>
is specified in read, write or copy modes,
<i>pax</i>
will write the
pathnames it processes to the standard error output using the
following format:
<code>
<p>
<tt>"%s\n"</tt>, &lt;<i>pathname</i>&gt;
</code>
<p>
These pathnames will be written as soon as processing is begun
on the file or archive member, and will be flushed to standard error.
The trailing
newline character,
which will not be buffered,
will be written when the file has been read or written.
<p>
If the
<b>-s</b>
option is specified, and the replacement string has
a trailing
p,
substitutions will be written to
standard error in the following format:
<code>
<p>
<tt>"%s<img src="../images/delta.gif" border=0>&gt;&gt;<img src="../images/delta.gif" border=0>%s\n"</tt>, &lt;<i>original pathname</i>&gt;,
&lt;<i>new pathname</i>&gt;
</code>
<p>
In all operating modes of
<i>pax</i>,
optional messages of unspecified format concerning
the input archive format and volume number,
the number
of files, blocks, volumes and media parts as well as other
diagnostic messages may be written to standard error.
<p>
In all formats, for both standard output and standard error, it is
unspecified how non-printable characters in pathnames or linknames
are written.
</blockquote><h4><a name = "tag_001_014_1699">&nbsp;</a>OUTPUT FILES</h4><blockquote>
In read mode,
the extracted or copied output
files are of the archived file type.
<p>
In write mode, the
output file named by the
<b>-f</b>
option-argument is a file
formatted according to one of the specifications in
the EXTENDED DESCRIPTION section,
or some other, implementation-dependent format.
</blockquote><h4><a name = "tag_001_014_1700">&nbsp;</a>EXTENDED DESCRIPTION</h4><blockquote>
<h5><a name = "tag_001_014_1700_001">&nbsp;</a>Extended cpio Format</h5>
The octet-oriented
<i><a href="cpio.html">cpio</a></i>
archive format is a series of entries,
each comprising a header
that describes the file, the name of the file and then the
contents of the file.
<p>
An archive may be recorded as a series of fixed-size blocks of octets.
This blocking will be used only to make physical
I/O
more efficient.
The last group of blocks always will be at the full size.
<p>
For the
octet-oriented
<i><a href="cpio.html">cpio</a></i>
archive format, the individual entry
information will be in the order indicated and described by
the following table:
<pre>
<table  bordercolor=#000000 border=1 align=center><tr valign=top><th align=center><b>Header Field Name</b>
<th align=center><b>Length (in Octets)</b>
<th align=center><b>Interpreted as</b>
<tr valign=top><td align=left><b>c_magic</b>
<td align=left>6
<td align=left>Octal number
<tr valign=top><td align=left><b>c_dev</b>
<td align=left>6
<td align=left>Octal number
<tr valign=top><td align=left><b>c_ino</b>
<td align=left>6
<td align=left>Octal number
<tr valign=top><td align=left><b>c_mode</b>
<td align=left>6
<td align=left>Octal number
<tr valign=top><td align=left><b>c_uid</b>
<td align=left>6
<td align=left>Octal number
<tr valign=top><td align=left><b>c_gid</b>
<td align=left>6
<td align=left>Octal number
<tr valign=top><td align=left><b>c_nlink</b>
<td align=left>6
<td align=left>Octal number
<tr valign=top><td align=left><b>c_rdev</b>
<td align=left>6
<td align=left>Octal number
<tr valign=top><td align=left><b>c_mtime</b>
<td align=left>11
<td align=left>Octal number
<tr valign=top><td align=left><b>c_namesize</b>
<td align=left>6
<td align=left>Octal number
<tr valign=top><td align=left><b>c_filesize</b>
<td align=left>11
<td align=left>Octal number
<tr valign=top><th align=left><b>Filename Field Name</b>
<th align=left>Length
<th align=left>Interpreted as
<tr valign=top><td align=left><b>c_name</b>
<td align=left>c_namesize
<td align=left>Pathname string
<tr valign=top><th align=left><b>File Data Field Name</b>
<th align=left>Length
<th align=left>Interpreted as
<tr valign=top><td align=left><b>c_filedata</b>
<td align=left>c_filesize
<td align=left>Data
</table>
</pre>
<h6 align=center><xref table="Octet-oriented <I>cpio</i> Archive Entry"></xref>Table: Octet-oriented <i>cpio</i> Archive Entry</h6>
<h5><a name = "tag_001_014_1700_002">&nbsp;</a>The cpio Header</h5>
For each file in the archive, a header as defined previously will be written.
The information in the header fields will be written as streams of the ISO/IEC&nbsp;646:1991 standard
characters interpreted as octal numbers.
The octal numbers
will be extended to the necessary length by appending the ISO/IEC&nbsp;646:1991 standard
IRV zeros at the most-significant-digit end of the number;
the result is written to the most-significant-digit of the stream of octets
first.
The fields are interpreted as follows:
<dl compact>

<dt><b>c_magic</b><dd>
Identify the archive as being a transportable archive
by containing the identifying value
070707.


<dt><b>c_dev</b><dd>
<dt><b>c_ino</b><dd>Contains values that uniquely identify
the file within the archive (that is, no files will contain the same
pair of
<b>c_dev</b>
and
<b>c_ino</b>
values unless they are links to the same file).
The values will be determined in an
unspecified manner.


<dt><b>c_mode</b><dd>Contains the file type and access permissions as defined
in the following table:
<pre>
<table  bordercolor=#000000 border=1 align=center><tr valign=top><th align=center><b>File Permissions Name</b>
<th align=center><b>Value</b>
<th align=center><b>Indicates</b>
<tr valign=top><td align=left>C_IRUSR
<td align=left>000400
<td align=left>Read by owner.
<tr valign=top><td align=left>C_IWUSR
<td align=left>000200
<td align=left>Write by owner.
<tr valign=top><td align=left>C_IXUSR
<td align=left>000100
<td align=left>Execute by owner.
<tr valign=top><td align=left>C_IRGRP
<td align=left>000040
<td align=left>Read by group.
<tr valign=top><td align=left>C_IWGRP
<td align=left>000020
<td align=left>Write by group.
<tr valign=top><td align=left>C_IXGRP
<td align=left>000010
<td align=left>Execute by group.
<tr valign=top><td align=left>C_IROTH
<td align=left>000004
<td align=left>Read by others.
<tr valign=top><td align=left>C_IWOTH
<td align=left>000002
<td align=left>Write by others.
<tr valign=top><td align=left>C_IXOTH
<td align=left>000001
<td align=left>Execute by others.
<tr valign=top><td align=left>C_ISUID
<td align=left>004000
<td align=left>Set <i>uid</i>.
<tr valign=top><td align=left>C_ISGID
<td align=left>002000
<td align=left>Set <i>gid</i>.
<tr valign=top><td align=left>C_ISVTX
<td align=left>001000
<td align=left>Reserved.
<tr valign=top><th align=left>File Type Name
<th align=left>Value
<th align=left>Indicates
<tr valign=top><td align=left>C_ISDIR
<td align=left>040000
<td align=left>Directory.
<tr valign=top><td align=left>C_ISFIFO
<td align=left>010000
<td align=left>FIFO.
<tr valign=top><td align=left>C_ISREG
<td align=left>0100000
<td align=left>Regular file.
<tr valign=top><td align=left>C_ISBLK
<td align=left>060000
<td align=left>Block special file.
<tr valign=top><td align=left>C_ISCHR
<td align=left>020000
<td align=left>Character special file.
<tr valign=top><td align=left>C_ISCTG
<td align=left>0110000
<td align=left>Reserved.
<tr valign=top><td align=left>C_ISLNK
<td align=left>0120000
<td align=left>Reserved.
<tr valign=top><td align=left>C_ISSOCK
<td align=left>0140000
<td align=left>Reserved.
</table>
</pre>
<h6 align=center><xref table="Values for <I>cpio</i> <b>c_mode</b> Field"></xref>Table: Values for <i>cpio</i> <b>c_mode</b> Field</h6>

Directories, FIFOs and regular files
are supported on a
system conforming to this specification;
additional values defined previously are
reserved for compatibility with existing systems.
Additional file types may be supported;
however, such files should not be
written to
archives intended to be transported to other systems.

<dt><b>c_uid</b><dd>Contains the user ID of the owner.

<dt><b>c_gid</b><dd>Contains the group ID of the group.

<dt><b>c_nlink</b><dd>Contains the number of links referencing
the file at the time the archive was created.

<dt><b>c_rdev</b><dd>Contains implementation-dependent information for character
or block special files.

<dt><b>c_mtime</b><dd>
Contains the latest time of modification of the file
at the time the archive was created.

<dt><b>c_namesize</b><dd>
Contains the length of the pathname, including the
terminating NUL character.

<dt><b>c_filesize</b><dd>
Contains the length of the file in octets.
This will be the length of the data section following the header structure.

</dl>
<h5><a name = "tag_001_014_1700_003">&nbsp;</a>The cpio Filename</h5>
The
<b>c_name</b>
field contains the pathname of the file.
The length of this field in octets is the value of
<i>c_namesize .</i>
If a filename
is found on the medium that would create an invalid pathname,
it is implementation-dependent if the data from the file is
stored on the file hierarchy and under what name it is stored.
<p>
All characters are represented in the ISO/IEC&nbsp;646:1991 standard IRV.
For maximum portability between implementations,
names should be selected from characters represented by the
portable filename character set
as octets with the most significant bit zero.
If an implementation supports the use of characters
outside the portable filename character set in names for
files, users and groups, one or more implementation-dependent
encodings of these characters will be provided for
interchange purposes.
However, the
<i>pax</i>
utility will never create
filenames on the local system that cannot be accessed via the
procedures described previously in this specification.
If a filename is found on the medium that would create an
invalid filename, it is implementation-dependent
if the data from the file is stored on the local file system
and under what name it is stored.
The
<i>pax</i>
utility may choose to ignore these files
as long as it produces an error indicating that the file is being ignored.
<h5><a name = "tag_001_014_1700_004">&nbsp;</a>The cpio File Data</h5>
Following
<i>c_name ,</i>
there are
<b>c_filesize</b>
octets of data.
Interpretation of such data occurs in a manner dependent on the file.
If
<b>c_filesize</b>
is zero, no data will be contained in
<i>c_filedata .</i>
<p>
When restoring from an archive:
<ul>
<p>
<li>
If the user does not have the appropriate privilege to create a
file of the specified type,
<i>pax</i>
will ignore the entry and write an error message to standard error.
<p>
<li>
Only regular files have data to be restored.
Presuming a
regular file meets any selection criteria that might be
imposed on the format-reading utility by the user, such data
will be restored.
<p>
<li>
If a user does not have appropriate privilege to set a
particular mode flag, the flag will be ignored.
Some of the
mode flags in the archive format are not mentioned elsewhere in
this specification.
If the implementation does not support those
flags, they may be ignored.
<p>
</ul>
<h5><a name = "tag_001_014_1700_005">&nbsp;</a>The cpio Special Entries</h5>
FIFO
special files, directories and the trailer are recorded with
<b>c_filesize</b>
equal to zero.
For other special files,
<b>c_filesize</b>
is unspecified by this specification.
The header for the next file entry
in the archive will be written directly
after the last octet of the file entry preceding it.
A header denoting the filename
TRAILER!!!
indicates
the end of the archive; the contents of octets in the last block of the
archive following such a header are undefined.
<h5><a name = "tag_001_014_1700_006">&nbsp;</a>Extended tar Format</h5>
An extended
<i><a href="tar.html">tar</a></i>
archive file contains a series of blocks.
Each block will be a fixed-size block of 512 octets (see below).
Each file archived is represented by a header block
that describes the file, followed by zero or more
blocks that give the contents of the file.
At the end of the archive file there will be two blocks filled with binary
zeros, interpreted as an end-of-archive indicator.
<p>
The blocks may be grouped for physical I/O operations.
Each group of
<i>n</i>
blocks (where
<i>n</i>
is set by the
<i>pax</i>
<b>-b</b>
option)
may be written with a single write operation.
On magnetic tape, the result of this write will be a single tape record.
The last group of blocks always will be at the full size, so
blocks after the two zero blocks may contain undefined data.
<p>
The header block will be structured as shown in the following table.
All lengths and offsets are in decimal.
<pre>
<table  bordercolor=#000000 border=1 align=center><tr valign=top><th align=center><b>Field Name</b>
<th align=center><b>Octet Offset</b>
<th align=center><b>Length (in Octets)</b>
<tr valign=top><td align=left><i>name</i>
<td align=left>0
<td align=left>100
<tr valign=top><td align=left><i>mode</i>
<td align=left>100
<td align=left>8
<tr valign=top><td align=left><i>uid</i>
<td align=left>108
<td align=left>8
<tr valign=top><td align=left><i>gid</i>
<td align=left>116
<td align=left>8
<tr valign=top><td align=left><i>size</i>
<td align=left>124
<td align=left>12
<tr valign=top><td align=left><i>mtime</i>
<td align=left>136
<td align=left>12
<tr valign=top><td align=left><i>chksum</i>
<td align=left>148
<td align=left>8
<tr valign=top><td align=left><i>typeflag</i>
<td align=left>156
<td align=left>1
<tr valign=top><td align=left><i>linkname</i>
<td align=left>157
<td align=left>100
<tr valign=top><td align=left><i>magic</i>
<td align=left>257
<td align=left>6
<tr valign=top><td align=left><i>version</i>
<td align=left>263
<td align=left>2
<tr valign=top><td align=left><i>uname</i>
<td align=left>265
<td align=left>32
<tr valign=top><td align=left><i>gname</i>
<td align=left>297
<td align=left>32
<tr valign=top><td align=left><i>devmajor</i>
<td align=left>329
<td align=left>8
<tr valign=top><td align=left><i>devminor</i>
<td align=left>337
<td align=left>8
<tr valign=top><td align=left><i>prefix</i>
<td align=left>345
<td align=left>155
</table>
</pre>
<h6 align=center><xref table="Extended <I>tar</i> Header Block"></xref>Table: Extended <i>tar</i> Header Block</h6>
<p>
All characters in the header block
are represented in the coded character set of the ISO/IEC&nbsp;646:1991 standard.
For maximum portability between implementations,
names should be selected
from characters represented by the
portable filename character set
as octets with the most significant bit zero.
If an implementation supports the use of characters
outside the portable filename character set in names for
files, users and groups, one or more implementation-dependent
encodings of these characters will be provided for
interchange purposes.
However, the
<i>pax</i>
utility will never create
filenames on the local system that cannot be accessed via the
procedures described previously in this specification.
If a filename is found on the medium that would create an
invalid filename, it is implementation-dependent
if the data from the file is stored on the file hierarchy
and under what name it is stored.
The
<i>pax</i>
utility may choose to ignore these files
as long as it produces an error indicating that the file is being ignored.
<p>
Each field within the
header block is contiguous;
that is, there is no padding used.
Each character on the archive medium is stored contiguously.
<p>
The fields
<b>magic</b>,
<b>uname</b>
and
<b>gname</b>
are character strings each terminated by a NUL character.
The fields
<b>name</b>,
<b>linkname</b>
and
<b>prefix</b>
are NUL-terminated character strings except when all characters
in the array contain non-NUL characters including the last character.
The
<b>version</b>
field is two octets containing the characters <b>00</b> (zero-zero).
The
<i>typeflag</i>
contains a single character.
All other fields
are leading zero-filled octal numbers
using digits from the ISO/IEC&nbsp;646:1991 standard IRV.
Each numeric field is terminated by one or more space
or NUL characters.
<p>
The
<b>name</b>
and the
<b>prefix</b>
fields produce the pathname of the file.
The hierarchical relationship of the file can be retained by specifying the
pathname as a path prefix, and a
slash character and filename as the suffix.
A new pathname is formed, if
<i>prefix</i>
is not an empty string (its first
character is not NUL), by concatenating
<i>prefix</i>
(up to the first NUL
character), a slash character and
<i>name ;</i>
otherwise,
<i>name</i>
is used alone.
In either case,
<i>name</i>
is terminated at the first NUL character.
If
<i>prefix</i>
begins with a NUL character, it will be ignored.
In this manner, pathnames of at most
256 characters can be supported.
If a pathname does not fit in the space provided,
<i>pax</i>
will notify the user of the error,
and will not store any part of the
file  header or data  on the medium.
<p>
The
<b>linkname</b>
field, described below, does not use the
<i>prefix</i>
to produce a pathname.
As such, a
<i>linkname</i>
is limited to
100 characters.
If the name does not fit in the space provided,
<i>pax</i>
will notify the user of
the error, and will not attempt to store
the link on the medium.
<p>
The
<b>mode</b>
field provides 12 bits encoded in the ISO/IEC&nbsp;646:1991 standard
octal digit representation.
The encoded bits represent the following values:
<dl compact>

<dt><b>04000</b><dd>Set UID on execution.

<dt><b>02000</b><dd>Set GID on execution.

<dt><b>01000</b><dd>Reserved.

<dt><b>00400</b><dd>Read by owner.

<dt><b>00200</b><dd>Write by owner.

<dt><b>00100</b><dd>Execute/search by owner.

<dt><b>00040</b><dd>Read by group.

<dt><b>00020</b><dd>Write by group.

<dt><b>00010</b><dd>Execute/search by group.

<dt><b>00004</b><dd>Read by other.

<dt><b>00002</b><dd>Write by other.

<dt><b>00001</b><dd>Execute/search by other.

</dl>
<p>
When appropriate privilege is
required to set one of these mode bits, and the user restoring the
files from the archive does not have the appropriate privilege,
the mode bits for which the user does not have appropriate privilege
will be ignored.
Some of the mode bits in the archive format
are not mentioned elsewhere in this specification.
If the implementation
does not support those bits, they may be ignored.
<p>
The
<b>uid</b>
and
<b>gid</b>
fields are the user and group ID
of the owner and group of the file, respectively.
<p>
The
<b>size</b>
field is the size of the file in octets.
If the
<b>typeflag</b>
field is set to specify a file to be of type
1
(a link)
or
2
(reserved for symbolic links),
the
<b>size</b>
field will be specified as zero.
If the
<b>typeflag</b>
field is set to specify a file of type
5
(directory), the
<b>size</b>
field will be interpreted as described under
the definition of that record type.
No data blocks will be stored for types
1,
2
or
5.
If the
<b>typeflag</b>
field is set to
3
(character special file),
4
(block special file),
or
6
(FIFO),
the meaning of the
<b>size</b>
field is unspecified by this specification, and no data
blocks will be stored on the medium.
Additionally, for
6,
the
<b>size</b>
field is ignored when reading.
If the
<b>typeflag</b>
field is set
to any other value,
<b>(size +511)/512</b>,
the number of blocks written following the header will be
ignoring any fraction in the result of the division.
<p>
The
<b>mtime</b>
field is the modification time of the file at the time
it was archived.
It is the ISO/IEC&nbsp;646:1991 standard representation of the octal value of the
modification time obtained from the <b>XSH</b> specification
<i><a href="../xsh/stat.html">stat()</a></i>
function.
<p>
The
<b>chksum</b>
field is the ISO/IEC&nbsp;646:1991 standard IRV representation of the octal value of the
simple sum of all octets in the header block.
Each octet in the header is treated as an unsigned value.
These values will be added to an unsigned integer,
initialised to zero, the precision of which will be not
less than 17 bits.
When calculating the
checksum, the
<b>chksum</b>
field is treated as if it were all spaces.
<p>
The
<b>typeflag</b>
field specifies the type of file archived.
If a
particular implementation does not recognise the type, or the
user does not have appropriate privilege to create that type,
the file will be extracted as if it were a regular file if the
file type is defined to have a meaning for the
<b>size</b>
field that could cause data blocks to be written on the medium (see the
previous description for
<i>size ).</i>
If conversion to a regular file occurs, the
<i>pax</i>
utility will produce
an error indicating that the conversion took place.
All of the
<b>typeflag</b>
fields will be coded in the ISO/IEC&nbsp;646:1991 standard IRV:
<dl compact>

<dt><b>'0'</b><dd>Represents a regular file.
For backward compatibility, a
<b>typeflag</b>
value of binary zero
('\0')
should be recognised as meaning a regular file
when extracting files from the archive.
Archives
written with this version of the archive file format
create regular files with a
<b>typeflag</b>
value of the ISO/IEC&nbsp;646:1991 standard IRV
0.

<dt><b>'1'</b><dd>Represents a file linked to another file, of
any type, previously archived.
Such files are
identified by each file having the same device and file serial number.
The linked-to name is specified in the
<b>linkname</b>
field with a NUL-character terminator if it is less than
100 octets in length.

<dt><b>'2'</b><dd>Reserved to represent a link to another file, of
any type, whose device or file serial number differs.
This is provided for systems that support linked files
whose device or file serial numbers differ, and should
be treated as a type
1
file if this extension does not exist.

<dt><b>'3','4'</b><dd>Represent character special files
and block special files respectively.
In this case the
<b>devmajor</b>
and
<b>devminor</b>
fields contain information defining the device, the
format of which is unspecified by this specification.
Implementations may map the device specifications to their own local
specification or may ignore the entry.

<dt><b>'5'</b><dd>Specifies a directory or subdirectory.
On systems where disk allocation is performed on a
directory basis, the
<b>size</b>
field will contain the maximum
number of octets (which may be rounded to the nearest
disk block allocation unit) that the directory may hold.
A
<b>size</b>
field of zero indicates no such limiting.
Systems that do not support limiting in this manner
should ignore the
<b>size</b>
field.

<dt><b>'6'</b><dd>Specifies a FIFO special file.
Note that the archiving of a FIFO file archives the
existence of this file and not its contents.

<dt><b>'7'</b><dd>Reserved to represent a file to which an implementation
has associated some high-performance attribute.
Implementations without such extensions should treat this
file as a regular file (type
0).

<dt><b>'A'-'Z'</b><dd>The letters
A
to
Z,
inclusive,
are reserved for custom implementations.
All other values are
reserved for specification in future issues.

</dl>
<p>
The
<b>magic</b>
field is the specification that this archive was output
in this archive format.
If this field contains
<b>ustar</b>
(the five characters from the ISO/IEC&nbsp;646:1991 standard IRV shown followed by NUL),
the
<b>uname</b>
and
<b>gname</b>
fields will contain the ISO/IEC&nbsp;646:1991 standard IRV
representation of the owner and group of the file respectively
(truncated to fit, if necessary).
When the file is restored by a privileged, protection-preserving
version of the utility,
the password and group files will be scanned for these names.
If found, the user and group IDs
contained within these
files will be used rather than the values contained
within the
<b>uid</b>
and
<b>gid</b>
fields.
</blockquote><h4><a name = "tag_001_014_1701">&nbsp;</a>EXIT STATUS</h4><blockquote>
The following exit values are returned:
<dl compact>

<dt>0<dd>All files were processed successfully.

<dt>&gt;0<dd>An error occurred.

</dl>
</blockquote><h4><a name = "tag_001_014_1702">&nbsp;</a>CONSEQUENCES OF ERRORS</h4><blockquote>
If
<i>pax</i>
cannot create a file or a link when reading an archive or
cannot find a file when writing an archive, or cannot preserve
the user ID, group ID or file mode when the
<b>-p</b>
option is
specified, a diagnostic message will be written to standard
error and a non-zero exit status will be returned, but
processing will continue.
In the case where
<i>pax</i>
cannot create a link to a file,
<i>pax</i>
will not, by default, create a second
copy of the file.
<p>
If the extraction of a file from an archive is prematurely
terminated by a signal or error,
<i>pax</i>
may have only partially
extracted the file or (if the
<b>-n</b>
option was not specified) may
have extracted a file of the same name as that specified by the
user, but which is not the file the user wanted.
Additionally,
the file modes of extracted directories may have additional
bits from the S_IRWXU mask set as well as incorrect modification
and access times.
</blockquote><h4><a name = "tag_001_014_1703">&nbsp;</a>APPLICATION USAGE</h4><blockquote>
The
<b>-p</b>
(privileges) option was invented to reconcile differences
between historical
<i><a href="tar.html">tar</a></i>
and
<i><a href="cpio.html">cpio</a></i>
implementations.
In particular, the two utilities use
<b>-m</b>
in diametrically opposed ways.
The
<b>-p</b>
option also provides a consistent means of
extending the ways in which
future file attributes can be addressed,
such as for enhanced security systems
or high-performance files.
Although it may seem complex, there are really
two modes that will be most commonly used:
<dl compact>

<dt><b>-p e</b><dd>&quot;Preserve everything&quot;.
This would be used by the historical superuser,
someone with all the appropriate privileges,
to preserve all aspects of the files as
they are recorded in the archive.
The
<b>e</b>
flag is the sum of
<b>o</b>
and
<b>p</b>,
and other implementation-dependent attributes.

<dt><b>-p p</b><dd>&quot;Preserve&quot; the file mode bits.
This would be used by the user with regular
privileges who wished to preserve aspects of
the file other than the ownership.
The file times are preserved by default,
but two other flags are offered to disable these
and use the time of extraction.

</dl>
<p>
The one pathname per line format of standard input precludes
pathnames containing
newline characters.
Although such pathnames violate
the portable filename guidelines, they may exist and their
presence may inhibit usage of
<i>pax</i>
within shell scripts.
This problem is inherited from historical archive programs.
The problem can be avoided by listing
filename arguments on the command line
instead of on standard input.
<p>
It is almost certain that appropriate privileges will be
required for
<i>pax</i>
to accomplish parts of this specification.
Specifically, creating files of type block special or character
special, restoring file access times unless the files are owned
by the user (the
<b>-t</b>
option) or preserving file owner, group,
and mode (the
<b>-p</b>
option) will all probably require appropriate privileges.
<p>
In read mode,
implementations are permitted to overwrite files when the
archive has multiple members with the same name.
This may fail if permissions on the first version of the file do
not permit it to be overwritten.
<p>
The
<i><a href="cpio.html">cpio</a></i>
and
<i><a href="tar.html">tar</a></i>
formats can only support files up to 8 gigabytes in size.
<p>
The 
<i>pax</i>
utility is not able to handle arbitrary file sizes. There is
currently a proposal in ballot in the IEEE PASC Shell and Utilities Working Group to address this
issue. 
</blockquote><h4><a name = "tag_001_014_1704">&nbsp;</a>EXAMPLES</h4><blockquote>
The following command:
<pre>
<code>
pax -w -f /dev/rmt/1m .
</code>
</pre>
copies the contents of the current directory to tape drive 1, medium density
(assuming
historical System&nbsp;V device naming procedures.
The historical
BSD device name would be
/dev/rmt9).
<p>
The following commands:
<pre>
<code>
mkdir <i>newdir</i>
pax -rw <i>olddir</i> <i>newdir</i>
</code>
</pre>
copy the
<i>olddir</i>
directory hierarchy to
<i>newdir .</i>
<p>
<pre>
<code>
pax -r -s ',^//*usr//*,,' -f a.pax
</code>
</pre>
reads the archive
<b>a.pax</b>,
with all files rooted in
<b>/usr</b>
in the archive extracted relative to the current directory.
</blockquote><h4><a name = "tag_001_014_1705">&nbsp;</a>FUTURE DIRECTIONS</h4><blockquote>
It is expected that future versions of the ISO/IEC 9945-2:1993 standard will
offer additional file formats and the
<b>-o</b>
option
will be used by future issues
to specify such features as international filename
and file codeset translations, security, accounting, and so on,
related to each additional format.
<p>
The 
<i>pax</i>
utility is not able to handle arbitrary file sizes. There is
currently a proposal in ballot in the IEEE PASC Shell and Utilities Working Group to address this
issue. 
</blockquote><h4><a name = "tag_001_014_1706">&nbsp;</a>SEE ALSO</h4><blockquote>
None.
</blockquote><hr size=2 noshade>
<center><font size=2>
UNIX &reg; is a registered Trademark of The Open Group.<br>
Copyright &copy; 1997 The Open Group
<br> [ <a href="../index.html">Main Index</a> | <a href="../xshix.html">XSH</a> | <a href="../xcuix.html">XCU</a> | <a href="../xbdix.html">XBD</a> | <a href="../cursesix.html">XCURSES</a> | <a href="../xnsix.html">XNS</a> ]

</font></center><hr size=2 noshade>
</body></html>
